Add documentation for resource customization by bmangoen · Pull Request #1292 · istio-ecosystem/sail-operator

bmangoen · 2025-10-21T11:44:16Z

What type of PR is this?

What this PR does / why we need it:

Add documentation section for resource customization including the sailoperator.io/ignore annotation usage and how it works
Remove a debug print statement in integration test

Which issue(s) this PR fixes:

* Add documentation section for resource customization including the sailoperator.io/ignore annotation usage and how it works * Remove a debug print statement in integration test Signed-off-by: bmangoen <bmangoen@redhat.com>

codecov · 2025-10-21T11:49:22Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.82%. Comparing base (5bf66f4) to head (0797f65).
⚠️ Report is 243 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1292      +/-   ##
==========================================
+ Coverage   77.59%   80.82%   +3.23%     
==========================================
  Files          44       53       +9     
  Lines        2834     2514     -320     
==========================================
- Hits         2199     2032     -167     
+ Misses        526      356     -170     
- Partials      109      126      +17

Flag	Coverage Δ
integration-tests	`71.30% <ø> (?)`
unit-tests	`51.31% <ø> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Added some more details about how the operator behaves when the sailoperator.io/ignore annotation is set to "true". Signed-off-by: bmangoen <bmangoen@redhat.com>

dgn · 2026-03-09T19:39:08Z

@bmangoen can we move this forward? @fjglira requested a small change, otherwise this LGTM

Signed-off-by: bmangoen <bmangoen@redhat.com>

bmangoen · 2026-03-16T09:28:08Z

@bmangoen can we move this forward? @fjglira requested a small change, otherwise this LGTM

@dgn @fjglira Sorry guys for this late change, I forgot about it and I didn't get notified... The ordered list should be fixed now

sridhargaddam

LGTM, thanks @bmangoen

dgn · 2026-04-09T10:48:58Z

+
+* **Ownership is preserved** - The resource must remain owned by its associated `Istio` (the ownerReference remains the associated `IstioRevision`)
+* **UPDATE event reconciliation is skipped** - The operator ignores update events for that specific resource, allowing manual modifications to persist
+* **CREATE and DELETE events remain active** - The annotation only affects UPDATE events; creation and deletion are processed normally (ie. the reconciliation will be triggered and all the changes will be reverted back to the state defined in the `Istio` or `IstioRevision` resource)


this is confusing. I kind of get the part of deletions but the why mentions the creations

Right, I removed this confusing point

dgn · 2026-04-09T10:49:25Z

+* `PodDisruptionBudget`
+
+[[limitations]]
+===== Limitations and Considerations


this entire section is basically the same as what was stated above

I removed the duplicated points. IMO these remaining ones should be mentioned, WDYT?

Signed-off-by: bmangoen <bmangoen@redhat.com>

nrfox

IMO this can be trimmed down a bit more. You can compare to how istio documents their resource annotations.

nrfox · 2026-04-17T12:51:28Z

+[[sailoperator-ignore-annotation]]
+==== sailoperator.io/ignore Annotation
+
+The `sailoperator.io/ignore` annotation allows you to prevent the Sail Operator from reconciling changes to specific resources that it manages. This is useful when you need to make manual modifications to operator-managed resources that should not be automatically reverted.


Suggested change

The `sailoperator.io/ignore` annotation allows you to prevent the Sail Operator from reconciling changes to specific resources that it manages. This is useful when you need to make manual modifications to operator-managed resources that should not be automatically reverted.

The `sailoperator.io/ignore` annotation allows you to prevent the Sail Operator from re-applying the helm charts in response to a change in one of the resources that it manages. This is useful when you or another controller needs to make modifications to operator-managed resources and the operator is continually overwriting the changes.

See these issues: https://github.com/istio-ecosystem/sail-operator/issues/430 and https://github.com/istio-ecosystem/sail-operator/issues/1148

This **does not** prevent the operator from re-applying the helm charts in response to other managed resources changing.

Signed-off-by: bmangoen <bmangoen@redhat.com>

nrfox

Looks good thanks @bmangoen

* upstream/main: Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1851) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1850) Add documentation for resource customization (istio-ecosystem#1292) refactor error and status condition handling (istio-ecosystem#1807) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1848) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1845) feat: add targetRef field to ZTunnel CRD (istio-ecosystem#1259) Add 1.29.2 and 1.28.6 versions (istio-ecosystem#1844) Use typed Go structs for FIPS values instead of helm.Values (istio-ecosystem#1695) Add helm.sh/helm/v3 to license allowlist alongside v4 (istio-ecosystem#1840) Update getLatestVersionByPrefix helm to v4 on update_deps.sh (istio-ecosystem#1833) Update kustomization files with registry.istio.io (istio-ecosystem#1829) Improve testing images tags for OLM and Operator images (istio-ecosystem#1819) Automator: Update EOL Istio versions in istio-ecosystem/sail-operator@main (istio-ecosystem#1821) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1820) Migrate from Helm v3 to Helm v4 (istio-ecosystem#1644) introduce crd-schema-checker (istio-ecosystem#1055) Add kubebuilder validation for revisionTagTargetRef (istio-ecosystem#1774) Handle errors in Helm discovery client (istio-ecosystem#1812) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1808)

* upstream/main: (23 commits) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1856) Modify "download-charts" script for alpha/beta releases (istio-ecosystem#1852) Add operator `TLSConfig` and sync with APIServer TLS profile on openshift (istio-ecosystem#1513) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1851) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1850) Add documentation for resource customization (istio-ecosystem#1292) refactor error and status condition handling (istio-ecosystem#1807) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1848) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1845) feat: add targetRef field to ZTunnel CRD (istio-ecosystem#1259) Add 1.29.2 and 1.28.6 versions (istio-ecosystem#1844) Use typed Go structs for FIPS values instead of helm.Values (istio-ecosystem#1695) Add helm.sh/helm/v3 to license allowlist alongside v4 (istio-ecosystem#1840) Update getLatestVersionByPrefix helm to v4 on update_deps.sh (istio-ecosystem#1833) Update kustomization files with registry.istio.io (istio-ecosystem#1829) Improve testing images tags for OLM and Operator images (istio-ecosystem#1819) Automator: Update EOL Istio versions in istio-ecosystem/sail-operator@main (istio-ecosystem#1821) Automator: Update dependencies in istio-ecosystem/sail-operator@main (istio-ecosystem#1820) Migrate from Helm v3 to Helm v4 (istio-ecosystem#1644) introduce crd-schema-checker (istio-ecosystem#1055) ...

Add documentation for resource customization

5fe2854

* Add documentation section for resource customization including the sailoperator.io/ignore annotation usage and how it works * Remove a debug print statement in integration test Signed-off-by: bmangoen <bmangoen@redhat.com>

bmangoen requested a review from a team as a code owner October 21, 2025 11:44

istio-testing added the size/L label Oct 21, 2025

dgn reviewed Oct 23, 2025

View reviewed changes

Comment thread docs/general/resource-customization.adoc Outdated

Clarify how sailoperator.io/ignore works

3e42417

Added some more details about how the operator behaves when the sailoperator.io/ignore annotation is set to "true". Signed-off-by: bmangoen <bmangoen@redhat.com>

fjglira reviewed Dec 2, 2025

View reviewed changes

Comment thread docs/general/resource-customization.adoc

sridhargaddam reviewed Mar 10, 2026

View reviewed changes

Comment thread docs/general/resource-customization.adoc Outdated

Comment thread docs/general/resource-customization.adoc Outdated

Fix ordered list

ecaac4b

Signed-off-by: bmangoen <bmangoen@redhat.com>

sridhargaddam reviewed Mar 17, 2026

View reviewed changes

dgn reviewed Apr 9, 2026

View reviewed changes

Comment thread docs/general/resource-customization.adoc Outdated

dgn reviewed Apr 9, 2026

View reviewed changes

Clarify How it Works part

101225d

Signed-off-by: bmangoen <bmangoen@redhat.com>

bmangoen requested review from dgn and nrfox April 16, 2026 15:19

nrfox reviewed Apr 17, 2026

View reviewed changes

Trim down parts

0797f65

Signed-off-by: bmangoen <bmangoen@redhat.com>

nrfox approved these changes Apr 17, 2026

View reviewed changes

istio-testing merged commit aa9e551 into istio-ecosystem:main Apr 17, 2026
17 checks passed

-The `sailoperator.io/ignore` annotation allows you to prevent the Sail Operator from reconciling changes to specific resources that it manages. This is useful when you need to make manual modifications to operator-managed resources that should not be automatically reverted.
+The `sailoperator.io/ignore` annotation allows you to prevent the Sail Operator from re-applying the helm charts in response to a change in one of the resources that it manages. This is useful when you or another controller needs to make modifications to operator-managed resources and the operator is continually overwriting the changes.
+See these issues: https://github.com/istio-ecosystem/sail-operator/issues/430 and https://github.com/istio-ecosystem/sail-operator/issues/1148
+This **does not** prevent the operator from re-applying the helm charts in response to other managed resources changing.

Conversation

bmangoen commented Oct 21, 2025

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Uh oh!

codecov Bot commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

dgn commented Mar 9, 2026

Uh oh!

Uh oh!

Uh oh!

bmangoen commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sridhargaddam left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dgn Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

bmangoen Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

dgn Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

bmangoen Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

nrfox left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nrfox Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

bmangoen Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nrfox left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov Bot commented Oct 21, 2025 •

edited

Loading

bmangoen commented Mar 16, 2026 •

edited

Loading